Version: REST API 2.15.0

Objects

Acquirer

Acquirer Enum

An enum representing the supported acquirers for merchant authentication.

Possible values

AMEX BORGUN EVO OMNIPAY POSTBRIDGE INTERAC TSYS VANTIV SANDBOX

Balance

Balance Object

Balance available on the card.

Properties

Property	Description
`amount` Integer	The balance
`currency` Currency	The balance currency
`positive` Boolean	Defines if the balance is positive
`negative` Boolean	Defines if the balance is negative

Code example

"balance": {
    "amount": 1000,
    "currency": "EUR",
    "negative": false,
    "positive": true
  }

Bypass Options

BypassOptions Object

Configuration to enable/disable signature or pin bypass.

Property Description

pinBypass
Boolean Enables/disables pin bypass. Bypasses PIN entry when the shopper says they don't know the PIN for the card and the merchant either knows they are the legitimate cardholder or want to give them the benefit of the doubt.

signatureBypass
Boolean Enables/disables signature bypass. Whether the terminal prompts for a signature, depends on how you configure this parameter. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature; they regard it as optional for card-present transactions. This means you can speed up your checkout by skipping the signature prompt. But if your business requires it, you can still let the terminal prompt for a signature. The shopper then provides their signature on the touch screen of the terminal or on the printed transaction receipt. This depends on how you configure this setting. It is your responsibility to verify the signature of the shopper with the signature on the card or another form of identification.

Property	Description
`pinBypass` Boolean	Enables/disables pin bypass. Bypasses PIN entry when the shopper says they don't know the PIN for the card and the merchant either knows they are the legitimate cardholder or want to give them the benefit of the doubt.
`signatureBypass` Boolean	Enables/disables signature bypass. Whether the terminal prompts for a signature, depends on how you configure this parameter. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature; they regard it as optional for card-present transactions. This means you can speed up your checkout by skipping the signature prompt. But if your business requires it, you can still let the terminal prompt for a signature. The shopper then provides their signature on the touch screen of the terminal or on the printed transaction receipt. This depends on how you configure this setting. It is your responsibility to verify the signature of the shopper with the signature on the card or another form of identification.

Code example

{
   "bypassOptions": {
       "signatureBypass": true,
       "pinBypass": true
       }
}

Card Entry Type

CardEntryType Enum

An enum representing different card entry types.

Possible values

UNDEFINED MSR ICC CNP

Card Scheme Name

CardSchemeName Enum

An enum representing different card brands.

Possible values

MasterCard Visa Maestro American Express Discover JCB Diners UnionPay Interac

Currency

Currency Enum

An enum of currencies.

Possible values

AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BOV BRL BSD BTN BWP BYR BZD CAD CDF CHF CLP CNY COP COU CRC CUC CUP CVE CZK DJF DKK DOP DZD EEK EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS INR IQD IRR ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MKD MMK MNT MOP MUR MVR MWK MXN MXV MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX VND VUV WST XAF XCD XOF XPF YER ZAR ZMK ZWL USD UZS VEF

Device

Device Object

An object to store information about the payment terminal in use. ALL values are REQUIRED.

Properties

Property	Description
`merchant_id_alpha` Required String	Merchant unique identifier associated with the payment terminal.
`serial_number` Required String	Payment terminal serial number.
`ssk` Required String	Payment terminal shared secret key to authenticate financial operations.
`terminal_type` Required String	Payment terminal name composed of two parts "serial_number - terminal_type".

Code example

{
       "merchant_id_alpha": "Test_Merchant",
       "serial_number": "614004878",
       "ssk": "74817EA5C63437ADE7AA3A5401",
       "terminal_type": "PAXA920"
}

Device Status

DeviceStatus Object

A class which holds the payment terminal status.

Properties

Property	Description
`SerialNumber` String	The serial number of the payment terminal.
`BatteryStatus` String	The battery status in percentages of the payment terminal.
`BatterymV` String	The battery milli volts of the payment terminal.
`BatteryCharging` String	The battery charging status of the payment terminal.
`ExternalPower` String	The status of the external power of the payment terminal.
`ApplicationName` String	The application name used on the payment terminal.
`ApplicationVersion` String	The application version number used on the payment terminal.
`bluetoothName` String	The bluetooth interface name used on the payment terminal.
`statusMessage` String	Device human readable status message.

Code example

{
    "applicationName": "TestApp",
    "applicationVersion": "20.1.0.1",
    "batteryCharging": "Charging",
    "batteryStatus": "100",
    "batterymV": "4134",
    "bluetoothName": "A920",
    "externalPower": "USB",
    "serialNumber": "0821032397",
    "statusMessage": "Card reader time out"
}

Financial Status

Financial Status Enum

An enum representing different statuses of a completed transaction.

UNDEFINED AUTHORISED DECLINED REFUNDED PROCESSED FAILED CANCELLED PARTIAL_APPROVAL IN_PROGRESS REFUNDED CAPTURED

Description of the different financial statuses:

Parameter	Notes
`UNDEFINED` (NOT FOUND) *	The `UNDEFINED` (NOT FOUND) status can be returned as a response to the get transaction status request. This status means that the transaction does not exist in the Handpoint gateway. If this status is returned within 90s of the start of a transaction, there could be a chance that the cardholder has not inserted, swiped or tapped his card yet on the terminal and the Handpoint gateway might soon receive the transaction. If the `UNDEFINED` status is returned after 90s, it means that the transaction processed has not reached the Handpoint gateway and it will NOT be charged..
`AUTHORISED`	The transaction (Sale, Refund etc.) has been authorised. Consider this value as "successful".
`DECLINED`	The transaction has been declined by the acquirer or issuer.
`PROCESSED`	The `printReceipt` operation was successful.
`FAILED`	Status generated due to a network error, a card which can not be read etc. As a general rule, errors are mapped to `FAILED`. This means the operation was unsuccessful and the transaction has not been charged.
`CANCELLED`	The transaction has been cancelled. For example if the `stopCurrentTransaction` operation has been used or the cancel button on the terminal has been pressed.
`PARTIAL_APPROVAL`	A partial approval is returned by the acquirer when funds have been partially authorized, for example if the cardholder does not have all the funds to cover the entire cost of the goods or services they are buying. The merchant can obtain the remainder of the purchase amount in another form of payment (cash, check or another card transaction for the remaining). `PARTIAL_APPROVAL` is only applicable to the United States market.
`IN_PROGRESS` *	The `IN_PROGRESS` status can be returned as a response to the get transaction status request. The transaction is known by the gateway but the result is not available yet. Please check the status again after a few seconds.
`REFUNDED` *	The `REFUNDED` status can be returned as a response to the get transaction status method. The original transaction (sale) has been refunded.
`CAPTURED`	The pre-authorization has been captured and funds are being moved to the merchant account. The `CAPTURED` financial status will only be returned in case a `preAuthorizationCapture` message was used to complete a pre-authorization. Regular Sales do NOT need to be captured and will not return a `CAPTURED` financial status

* Financial statuses marked with an asterisk (*) can only be returned as a response to the get transaction status method.

Merchant Auth

MerchantAuth Object

An object used to store merchant authentication parameters. This object is optional, it allows a transaction to be funded to a specific merchant account other than the default one. It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office.

Property	Description
`Credential` Credential[]	Array of credentials

Code example

{
   "merchantAuth": [{
       "acquirer": "ACQ_DUMMY",
       "mid": "1111",
       "tid": "2222",
       "mcc": "3333",
       "externalId": "4444"
       }]
}

Merchant Auth Credential

Credential Object

An object to store credentials (Acquirer, Mid, Tid, MCC and ExternalId) for merchant authentication.

Properties

Property	Description
`acquirer` Acquirer	If present, it links this credential to the specified acquirer. Only required if more than one credential is provided.
`mid` String	For this transaction, overrides the default MID (merchant ID) saved in the terminal configuration.
`tid` String	For this transaction, overrides the default TID (terminal ID) saved in the terminal configuration.
`mcc` String	Merchant Category Code, overrides the default MCC saved in the terminal configuration.
`ExternalId` String	For this transaction, the External Id will be used to lookup the credential of the merchant in the Handpoint backend and process the transaction accordingly. The External id replaces the need to pass MID/TID/MCC as credentials

Code example

{
    "acquirer": "ACQ_DUMMY",
    "mid": "1111",
    "tid": "2222",
    "mcc": "3333"
}

{
    "externalId": "4444"
}

Metadata

Metadata Object

An object to store metadata.

Properties

Property	Description
`metadata1` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata2` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata3` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata4` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata5` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`

Code example

{
    "metadata": {
        "metadata1": "data1",
        "metadata2": "data2",
        "metadata3": "data3",
        "metadata4": "data4",
        "metadata5": "data5"
    }
}

Operation Type

OperationType Enum

An enum representing different types of operations.

Possible Values:

sale refund refundReversal saleReversal saleAndTokenizeCard tokenizeCard printReceipt update cardPan pingDevice stopCurrentTransaction moToSale moToRefund moToReversal moToPreAuthorization preAuthorization preAuthorizationIncrease preAuthorizationCapture preAuthorizationReversal

Operation Types Description

OperationTypesDescription

Parameter	Notes
`sale` String	Sends a sale transaction to the payment terminal. This is the most basic operation used to withdraw funds from the cardholder's bank account.
`refund` String	Sends a refund transaction to the payment terminal. This operation moves funds from the merchant account to the cardholder´s credit card. For Interac (Canadian Debit Network), refunds can only be processed until Interac closes the batch of transactions at night.
`refundReversal` String	A refund reversal, also called refund VOID, allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id.
`saleReversal` String	A sale reversal, also called sale VOID allows the merchant to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id.
`saleAndTokenizeCard` String	A sale operation which also returns a card token. This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice.
`tokenizeCard` String	Returns a card token (representing the card number). This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice.
`printReceipt` String	Print on demand functionality allowing the merchant to print any HTML formatted receipt. It is possible to print images or barcodes as well as passing directly a URL to the printReceipt function. A bitmap can also be printed, in order to do so it needs to be rendered as an image and inserted into the html. The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats. The format of the HTML data, stored in the URL or passed in the value of the `receipt` key, must follow this format: HTML Print Format
`update` String	The update operation checks for new software or configuration updates and initiates a download if required.
`cardPan` String	A cardPan request will return the full PAN of the card being swiped, dipped or tapped. Only the PANs of whitelisted card ranges will be returned by the Handpoint systems. This operation is mostly used to be able to process funds or points from loyalty cards.
`pingDevice` String	This operation will ping the terminal to confirm if it is online.
`stopCurrentTransaction` String	Operation used to stop the current transaction. The transaction can only be stopped at specific stages of payment processing, for example a transaction can not be stopped when the card is being read but can be stopped when waiting for the cardholder to initially insert a card.
`moToSale` String	Mail Order /Telephone Order (MOTO) sale. MOTO is a type of card-not-present (CNP) transaction in which services are paid and delivered via telephone, mail, fax, or internet communication. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase.
`moToRefund` String	A MOTO refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts the original transaction id. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO Refund is a type of card-not-present (CNP) transaction in which services are refunded via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase or refund.
`moToReversal` String	A MOTO reversal, also called VOID allows the user to reverse a previous MOTO sale/refund operation. This operation reverts (if possible) a specific operation identified with a transaction id. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. MOTO Reversal is a type of card-not-present (CNP) transaction used to reverse a previous MOTO Sale or MOTO Refund.
`moToPreAuthorization` String	A MOTO pre-authorization, sends a pre-authorization transaction to the payment terminal. A pre-authorization charge is a temporary hold placed on a customer’s payment card. It’s used to verify that the account is valid and has sufficient funds to cover a pending transaction.
`preAuthorization` String	A pre-auth initiates a pre-authorization operation to the card reader. In it's simplest form you only have to pass the amount and currency but it also accepts tip configuration and a map with extra parameters. A pre-authorization charge, also known as a pre-auth or authorization hold, is a temporary hold placed on a customer's payment card. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront.
`preAuthorizationIncrease` String	This operation allows the merchant to increase/decrease the amount of a previously performed pre-auth operation. For example, if a tab was opened at a restaurant and the consumer is adding new orders going above the initial pre-authorized amount, it is required to increase the amount of the initial pre-authorization before capturing it. If the merchant wants to release part of a pre-auth, an increase with negative amount should be passed to the function.
`preAuthorizationCapture` String	A pre-authorized transaction can be captured to actually debit the cardholder's account. Depending on the merchant category code, the capture needs to happen between 7 and 31 days after the original pre-authorization. If not captured the funds will be automatically released by the issuing bank. Please note that a pre-authorization can only be captured ONCE, multiple partial captures are not allowed. If for some reason, the pre-authorization was captured for an incorrect amount, you can attempt to reverse the capture (does not work with all acquirers). If the capture reversal was declined, the cardholder needs to come back into the store with his card to get refunded or re-authorize the transaction. Alternatively, the cardholder can give his card details over the phone to the merchant and a MOTO pre-auth or MOTO refund can be issued. Check out the card brand rules.
`preAuthorizationReversal` String	A Pre-Auth/Capture Reversal allows the user to reverse a previous pre-auth operation. This operation reverts (if possible) a specific pre-auth identified with a transaction id. A pre-authorized reversal transaction will release the whole pre-authorized amount, for example when renting a car, the pre-auth reversal allows the merchant to release the funds if the car was not damaged. For partial releases, please check the Pre-Auth Increase/Decrease operation. A Pre-Auth/Capture reversal can be used to reverse a capture operation as well. A capture reversal transaction will release all the funds withheld. Reversing a capture operation can only be done before the funds are automatically settled at night, please note that not all acquirers support reversal of captured transactions. If a capture reversal is attempted after the funds have been moved, the operation will receive a decline. When the capture is reverted it returns to the previous state (CAPTURED -> AUTHORISED).

Pre-Auth Capture Card Brand Rules

Card schemes set specific rules around which businesses are able to use pre-auth transactions. Eligibility is determined based on the Merchant Category Code (MCC), together with the card scheme.

Card schemes have their own set of rules on authorisation expiry. Capturing a transaction after the scheme expiry time increases the risk of a failed capture, and may also increase the interchange and/or scheme fees charged for the transaction. Card schemes can also expire an authorisation before or after the official scheme expiry period has been reached. You can often capture a payment successfully after an authorisation has expired. Depending on the card scheme, there can be a fee for late capture, and an increase in interchange fee. The risk of cardholder chargebacks increase as well.

Scheme	MCC
Mastercard	All MCCs except 5542
Visa	All MCCs except 5542
Discover	3351-3441, 3501-3999, 4111, 4112, 4121, 4131, 4411, 4457, 5499, 5812, 5813, 7011, 7033, 7996, 7394, 7512, 7513, 7519, 7999
American Express	All MCCs except 5542

VISA rules

MCC	Segment	Authorization timeframe	Amount tolerance (captured amount above pre-authorized amount)
3501-3999, 7011	Lodging	31 days	15%
3351-3500, 7512	Car Rental	31 days	15%
4411	Steamship and Cruise Lines	31 days	15%
7513	Truck Rentals	7 days	15%
7033	Trailer Parks and Campgrounds	7 days	15%
7519	Motor Home and Recreational Vehicle Rentals	7 days	15%
5552	Electric Vehicle Charging	7 days	15%
7523	Parking and Garages	7 days	15%
7394	Equipment, Tool, Furniture and Appliance Rental	7 days	none
7999	Recreation Services	7 days	none
7996	Amusement Parks, Carnivals, Circuses, Fortune Tellers	7 days	none
5599	Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers	7 days	none
4457	Boat Rentals and Leasing	7 days	none
5571	Motorcycle Shops and Dealers	7 days	none
4111	Local and Suburban Commuter, Passenger Transportation, including Ferries	7 days	25 USD (or equivalent amount in local currency)
4112	Passenger Railways	7 days	25 USD (or equivalent amount in local currency)
4131	Bus Lines	7 days	25 USD (or equivalent amount in local currency)
5812	Eating Places and Restaurants	Same day	20%
5813	Drinking Places, Bars, Taverns, Cocktail Lounges, Nightclubs, Discotheques	Same day	20%
4121	Taxicabs and Limousines (Card-Absent Environment only)	Same day	20%

MASTERCARD rules

MCC	Authorization timeframe	Amount tolerance (captured amount above pre-authorized amount)
All MCCs	30 days	20%

Maestro rules

MCC	Segment	Authorization timeframe	Amount tolerance (captured amount above pre-authorized amount)
5812	Eating Places and Restaurants	7 days	20%
5814	Fast Food Restaurants	7 days	20%

AMEX rules

MCC	Authorization timeframe
All MCCs	7 days

Note: Pre-Auth with AMEX is only available in the United States/Canada with the processor TSYS.

Discover rules

MCC	Authorization timeframe
Car Rental, Hotel/Lodging MCCs	30 days
All MCCs except Car Rental and Hotel/Lodging	10 days

Diners rules

MCC	Debit/credit	Authorization timeframe
Car Rental, Hotel/Lodging MCCs	All	30 days
All MCCs except Car Rental and Hotel/Lodging	Credit	30 days
All MCCs except Car Rental and Hotel/Lodging	Debit	7 days

JCB rules

MCC	Authorization timeframe
Hotel and Car rental	Time of stay/rental
All MCCs except Hotel and Car rental	1 year

Payment Scenario

PaymentScenario Enum

An enum representing different types of payment scenario.

Possible values

UNKNOWN MAGSTRIPE MAGSTRIPECONTACTLESS CHIP CHIPCONTACTLESS CHIPFAILMAGSTRIPE MOTO

Status

status Enum

An enum containing information about the status of a transaction.

Possible values

Undefined Success InvalidData ProcessingError CommandNotAllowed NotInitialised ConnectTimeout ConnectError SendingError ReceivingError NoDataAvailable TransactionNotAllowed UnsupportedCurrency NoHostAvailable CardReaderError CardReadingFailed InvalidCard InputTimeout UserCancelled InvalidSignature WaitingForCard CardInserted ApplicationSelection ApplicationConfirmation AmountValidation PinInput ManualCardInput WaitingForCardRemoval TipInput SharedSecretInvalid SharedSecretAuth WaitingSignature WaitingHostConnect WaitingHostSend WaitingHostReceive WaitingHostDisconnect PinInputCompleted PosCancelled RequestInvalid CardCancelled CardBlocked RequestAuthTimeout RequestPaymentTimeout ResponseAuthTimeout ResponsePaymentTimeout IccCardSwiped RemoveCard ScannerIsNotSupported ScannerEvent BatteryTooLow AccountTypeSelection BtIsNotSupported PaymentCodeSelection PartialApproval AmountDueValidation InvalidUrl WaitingCustomerReceipt PrintingMerchantReceipt PrintingCustomerReceipt UpdateStarted UpdateFinished UpdateFailed UpdateProgress WaitingHostPostSend WaitingHostPostReceive Rebooting PrinterOutOfPaper ErrorConnectingToPrinter CardTapped ReceiptPrintSuccess InvalidPinLength OfflinePinAttempt OfflinePinLastAttempt ProcessingSignature CardRemoved TipEntered CardLanguagePreference AutomaticPrintingStarted CancelOperationNotAllowed UpdateSoftwareStarted UpdateSoftwareFinished UpdateSoftwareFailed UpdateSoftwareProgress InstallSoftwareStarted InstallSoftwareFinished InstallSoftwareFailed InstallSoftwareProgress UpdateConfigStarted UpdateConfigFinished UpdateConfigFailed UpdateConfigProgress InitialisationComplete

Status Info

StatusInfo Object

A class containing information about the status of the transaction.

Properties

Property	Description
`cancelAllowed` boolean	A `boolean` Letting the integrator know if the terminal will accept a stop transaction request.)
`status` Status	A `Status` enum representing the status of the transaction.
`message` String	A `String` containing the status message of the transaction.
`deviceStatus` DeviceStatus	A `DeviceStatus` object containing information about the payment terminal.

Tender Type

TenderType Enum

An enum representing different tender types.

Possible values

NOT_SET CREDIT DEBIT

Tip Adjustment

TipAdjustment Object

Property	Description
`amount` Biginteger	Exact amount of the tip, including decimal digits. Currency will be extracted from the original transaction.

Code example

{
    "amount": 10.25
}

{
    "amount": 20
}

Tip Configuration

TipConfiguration Object

Property	Description
`baseAmount` String	Base amount used to calculate the tip - in the minor unit of currency (f.ex. 1000 is 10.00 GBP). If no base amount is defined, the transaction amount is used as base amount.
`headerName` String	Name of the tipping menu appearing on the terminal. Default: Tip
`tipPercentages` Required List	List of percentages used to calculate the tip amount.
`enterAmountEnabled` boolean	Flag used to enable the cardholder to manually enter the tip amount. Default: true
`skipEnabled` Boolean	Flag used to enable the cardholder to skip the tipping step. Default: true
`footer` String	Footer note which will appear on the tipping menu. Default: Empty string

Code example

{
    "tipConfiguration":{
       "baseAmount":"2000",
       "headerName":"",
       "tipPercentages":[
          5,
          10,
          15,
          20,
          25
       ],
       "enterAmountEnabled":true,
       "skipEnabled":false,
       "footer":"Thank you!!! ;)"
    }
 }

Transaction Request Object

TransactionRequest Object

An object to store information about the request sent to the payment terminal.

Properties

Property	Description
`operation` Required OperationTypesDescription	The type of operation to be performed.
`serial_number` Required String	Payment terminal serial number.
`terminal_type` Required String	Type of terminal.
`callbackUrl` String	If used,this is the url the payment terminal will use to send the Transaction Result once the operation is complete. All 2XXs http response codes from the callbackUrl (your server) are valid to notify the terminal of a successful delivery of the result. If the callbackUrl is not present, the device will send back the transaction result to Handpoint's REST-API and results can be retrieved using the Transaction Result Retrieval endpoint.
`token` String	If used, the token is a unique value per operation generated by your software and used to authenticate the transaction result sent through the callbackUrl against your server. The token will be injected in the request header with key value 'AUTH-TOKEN'. REQUIRED when the callbackUrl is present.
`customerReference` String	Transaction identifier provided by your software. The customerReference sent in the TransactionRequest object is echoed in the TransactionResult. In case the transaction outcome is unknown (network issue or other) and for some unknown reason your software did not receive any result. The customerReference can be used to query the Handpoint Transaction API and check if a specific transaction was approved or not: https://txnfeedapi.handpoint.com/#api-Transactions-getTxnByCustomerReference.
`amount` String	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP). REQUIRED for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard.
`currency` Currency	The currency of the transaction. REQUIRED for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard.
`originalTransactionId` String	The transaction id of the original operation to be reversed. Only required to reverse or refund a transaction and for operations linked to a pre-authorisation. REQUIRED for operations: refundReversal, saleReversal, LINKED refunds, preAuthorizationIncrease, preAuthorizationCapture and preAuthorizationReversal.
`receipt` String	HTML receipt, following the format defined in Html Print Format, or url to locate the receipt, it can be found in the response of a Transaction Request, in the fields merchantReceipt or customerReceipt. REQUIRED for operations: printReceipt. The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats.
`tipConfiguration` TipConfiguration	Configuration to enable tipping. At the time of sale, a tip menu will be shown to the cardholder with the predefined configuration. The tip configuration is optional and can only be used with the sale and saleAndTokenize operations.
`bypassOptions` ByPassOptions	Configuration to enable the possibility of bypassing signature or pin. The bypass configuration is optional and can only be used with the sale, saleAndTokenize and refund operations.
`merchantAuth` MerchantAuth	Object used to store merchant authentication. it allows a transaction to be funded to a specific merchant account other than the default one. It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office. The merchantAuth is optional and can only be used with the sale, saleAndTokenize and refund operations. For reversals, the credentials passed for the original sale will be automatically looked up by Handpoint and used to process the reversal.
`duplicate_check` Boolean	Used to disable the duplicate payment check functionality. When a merchant is not 100% sure of the transaction outcome, they will reprocess the transaction leading to the cardholder being charged twice. In order to avoid this scenario, we are flagging the duplicate transaction and prompting a menu to the cardholder/merchant to confirm/cancel the second charge. This menu will automatically be prompted on the payment terminal if a suspicious charge is detected. We are only prompting the duplicate check menu in case the same card is used twice in a row to process a transaction for the same amount within a 5 minutes timeframe. The duplicate_check functionality is available for the following transaction types: Sale, Sale and Tokenize, Sale Reversal, Refund, Refund Reversal, MoTo Sale, MoTo Refund and MoTo Reversal. The `duplicate_check` service is enabled to "true" by default, if you want to disable it, you must explicitly pass the `duplicate_check` flag as part of the transaction request with the value "false".
`metadata` Metadata	Object used to store metadata, this data will be echoed in the transaction result. Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`transactionReference` String	The `transactionReference` is a unique (UUID v4) that you need to generate and add to every transaction request. In case something goes wrong and you do not receive a transaction result from the terminal, you will be able to query the Handpoint gateway directly with this id by using the get transaction status endpoint.

Code example

// Result will be served to result.com
{
       "operation": "sale",
       "amount": "10000",
       "currency": "EUR",
       "terminal_type": "PAXA920",
       "serial_number": "1547854757",
       "customerReference": "storeSale12548",
       "callbackUrl": "https://result.com",
       "token": "123456789",
       "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f",
       "tipConfiguration": {
              "baseAmount": "2000",
              "tipPercentages": [5,10,15,20,25],
              "enterAmountEnabled": true,
              "skipEnabled": false,
              "footer": "Thank you!!! ;)"
           },
       "bypassOptions": {
              "signatureBypass": true,
              "pinBypass": true
           },
       "merchantAuth": [{
              "acquirer": "ACQ_DUMMY",
              "mid": "1111",
              "tid": "2222",
              "mcc": "3333",
              "externalId": "4444"
           }],
        "duplicate_check": true,
        "metadata": {
            "metadata1": "data1",
            "metadata2": "data2",
            "metadata3": "data3",
            "metadata4": "data4",
            "metadata5": "data5"
        }   
}

// Result will be served back to Handpoint's REST-API
{
       "operation": "sale",
       "amount": "10000",
       "currency": "EUR",
       "terminal_type": "PAXA920",
       "serial_number": "1547854757",
       "customerReference": "storeSale12548",
       "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f",
       "tipConfiguration": {
              "baseAmount": "2000",
              "tipPercentages": [5,10,15,20,25],
              "enterAmountEnabled": true,
              "skipEnabled": false,
              "footer": "Thank you!!! ;)"
           },
       "bypassOptions": {
              "signatureBypass": true,
              "pinBypass": true
           },
       "merchantAuth": [{
              "acquirer": "ACQ_DUMMY",
              "mid": "1111",
              "tid": "2222",
              "mcc": "3333",
              "externalId": "4444"
           }],
        "duplicate_check": true,
        "metadata": {
            "metadata1": "data1",
            "metadata2": "data2",
            "metadata3": "data3",
            "metadata4": "data4",
            "metadata5": "data5"
        }   
}

Transaction Result Object

TransactionResult Object

An object holding information about the result of a transaction.

tip

signatureUrl: In case the signature can not be updated to the Handpoint servers and an URL is not generated, the terminal will send back the image binary in base64 format to your software. It is important to be able to support both the URL and the image binary format.

customerReceipt and merchantReceipt: The receipts are usually received as URLs in the transaction result from the terminal. Please note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and an URL is not generated then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats.

Properties

Property	Description
`aid` String	EMV Application Identifier of the card (EMV tag 9F06)
`arc` String	EMV Authorisation Response Code (EMV tag 8A)
`authorisationCode` String	Acquirer response code
`balance` Balance	Balance available on the card
`budgetNumber` String	Used to split payments over a period of months
`cardEntryType` CardEntryType	Method used by the terminal to read the card
`cardLanguagePreference` String	Preferred language of the card (EMV tag 5F2D)
`cardSchemeName` CardSchemeName	The brand of the card
`cardToken` String	Token representing the PAN of the card
`chipTransactionReport` String	Full report of the card EMV parameters
`currency` Currency	The currency used for the transaction
`customerReceipt` String	The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats.
`customerReference` String	If a customerReference was provided as an optional parameter in the transaction request it is echoed unaltered in this field
`deviceStatus` DeviceStatus	Status of the payment terminal
`dueAmount` BigInteger	In case of a partial approval for the transaction, this field contains the amount which remains to be paid. Partial approval support is only required by the card brands in the United States
`efttimestamp` BigInteger	Time of the transaction (based on the date and time of the payment terminal)
`efttransactionID` String	Handpoint unique identifier for a transaction, this id is the one to be used for a transaction to be reversed.
`errorMessage` String	Detailed reason for the transaction error
`expiryDateMMYY` String	Expiry date of the card used for the operation
`finStatus` FinancialStatus	The financial status contains the outcome of the transaction. For example "AUTHORISED" or "DECLINED"
`iad` String	EMV Issuer Application Data (EMV tag 9F10)
`issuerResponseCode` String	Response code from the card issuer
`maskedCardNumber` String	Masked card number of the card used for the operation
`merchantAddress` String	Merchant Address
`merchantName` String	Merchant Name
`merchantReceipt` String	The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats.
`metadata` Metadata	If metadata was provided as an optional parameter in the transaction request it is echoed unaltered in this field
`mid` String	Merchant Identifier
`originalEFTTransactionID` String	In case the transaction type is a reversal, this field will contain the identifier of the original transaction being reversed
`paymentScenario` PaymentScenario	Indicates the card entry mode
`recoveredTransaction` Boolean	This flag is set to true if the transaction result is sent through the transaction recovery logic explained in the Recovey Section, false otherwise
`requestedAmount` BigInteger	The requested amount is the transaction amount sent to the terminal
`rrn` String	Retrieval Reference Number, unique number assigned by the acquirer
`signatureUrl` String	If a digital signature is required, this is the URL containing the image of the captured signature. In case the signature can not be updated to the Handpoint servers and an URL is not generated, the terminal will send back the image binary in base64 format to your software. It is important to be able to support both the URL and the image binary format.
`statusMessage` String	The status of the transaction, for example "Waiting for pin"
`tenderType` TenderType	Transaction tender type (credit / debit)
`tid` String	Terminal Identifier
`tipAmount` BigInteger	Tip amount, if any, in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
`tipPercentage` Double	If tipping is enabled, this field will return the tip percentage added on top of the base amount
`totalAmount` BigInteger	The total amount is the amount the card was charged for. It is possible that the total amount is not the same as the requested amount since an additional fee can be added, with the customer's approval, via the tipping functionality
`transactionID` String	The transaction id is a terminal internal counter incremented for each transaction
`tsi` String	EMV Transaction Status Information (EMV tag 9B)
`tvr` String	EMV Transaction Verification Results (EMV tag 95)
`type` TransactionType	The type of transaction initiated, for example "SALE"
`unMaskedPan` String	Unmasked PAN, only received if the card is a non-payment card (loyalty)
`verificationMethod` VerificationMethod	cardholder verification method, for example "PIN"
`multiLanguageStatusMessages` Map	`map` containing the status message in a human readable format for all the supported locales.
`multiLanguageErrorMessages` Map	`map` containing the error message in a human readable format for all the supported locales.
`cardHolderName` String	Name of the cardholder
`transactionReference` String	The unique UUID associated with the transaction, it can be used to query the get transaction status endpoint.

Code example

{
  "aid": "A0000000041010",
  "arc": "0000",
  "authorisationCode": "123456",
  "balance": null,
  "budgetNumber": "",
  "cardEntryType": "UNDEFINED",
  "cardLanguagePreference": "",
  "cardSchemeName": "MasterCard",
  "cardToken": "",
  "chipTransactionReport": "",
  "currency": "USD",
  "customerReceipt": "https://s3.[...]/customerReceipt.html",
  "customerReference": "",
  "deviceStatus": {
      "applicationName": "ClientApp",
      "applicationVersion": "20.1.0",
      "batteryCharging": "Not Charging",
      "batteryStatus": "100",
      "batterymV": "4126",
      "bluetoothName": "PAXA920",
      "externalPower": "USB",
      "serialNumber": "0821032398",
      "statusMessage": "Approved or completed successfully"
  },
  "dueAmount": 0,
  "errorMessage": "",
  "expiryDateMMYY": "0422",
  "finStatus": "AUTHORISED",
  "iad": "0210A000002A0000000000000000000000FF",
  "issuerResponseCode": "00",
  "maskedCardNumber": "************1456",
  "merchantAddress": "Plaza Soledad Torres Acosta 1 28013 Madrid",
  "merchantName": "Hago la cama",
  "merchantReceipt": "https://s3.[...]/merchantReceipt.html",
  "metadata": {
      "metadata1": "data1",
      "metadata2": "data2",
      "metadata3": "data3",
      "metadata4": "data4",
      "metadata5": "data5"
  },
  "mid": "",
  "originalEFTTransactionID": "",
  "paymentScenario": "CHIPCONTACTLESS",
  "rrn": "",
  "signatureUrl": "",
  "statusMessage": "Approved or completed successfully",
  "tenderType": "CREDIT",
  "tid": "ACQUIRER_TID",
  "tipAmount": 0,
  "totalAmount": 100,
  "transactionID": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
  "tsi": "0000",
  "tvr": "0400008001",
  "type": "SALE",
  "unMaskedPan": "",
  "verificationMethod": "UNDEFINED",
  "efttimestamp": 1615374961000,
  "efttransactionID": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
  "requestedAmount": 100,
  "tipPercentage": 0,
  "recoveredTransaction": false,
  "cardHolderName": "Mr/Mrs card holder full name",
  "transactionReference": "3e665342-a95b-49c1-b6fe-b3f102305a76"
}

Transaction Type

TransactionType Enum

An enum representing different types of transactions.

Possible values

UNDEFINED SALE VOID_SALE REFUND VOID_REFUND CANCEL_SALE CANCEL_REFUND TOKENIZE_CARD CARD_PAN CANCEL_TRX MOTO_SALE MOTO_REFUND MOTO_REVERSAL

Verification Method

VerificationMethod Enum

An enum representing the possible verification methods used during the transaction.

Possible values:

UNDEFINED SIGNATURE PIN PIN_SIGNATURE FAILED NOT_REQUIRED MOBILE_PASS_CODE

Objects

Acquirer​

Balance​

Bypass Options​

Card Entry Type​

Card Scheme Name​

Currency​

Device​

Device Status​

Financial Status​

Merchant Auth​

Merchant Auth Credential​

Metadata​

Operation Type​

Operation Types Description​

Pre-Auth Capture Card Brand Rules​

Payment Scenario​

Status​

Status Info​

Tender Type​

Tip Adjustment​

Tip Configuration​

Transaction Request Object​

Transaction Result Object​

Transaction Type​

Verification Method​

Acquirer

Balance

Bypass Options

Card Entry Type

Card Scheme Name

Currency

Device

Device Status

Financial Status

Merchant Auth

Merchant Auth Credential

Metadata

Operation Type

Operation Types Description

Pre-Auth Capture Card Brand Rules

Payment Scenario

Status

Status Info

Tender Type

Tip Adjustment

Tip Configuration

Transaction Request Object

Transaction Result Object

Transaction Type

Verification Method